home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / QuickTime / QuickTime 3 Interfaces & Libs / QTDevWin / CIncludes / NameRegistry.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-21  |  14.1 KB  |  495 lines  |  [TEXT/dosa]
  1. /*
  2.      File:        NameRegistry.h
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    Technology:    MacOS
  7.                  Release:    QuickTime 3.0
  8.  
  9.      Copyright:    © 1993-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __NAMEREGISTRY__
  19. #define __NAMEREGISTRY__
  20.  
  21. #ifndef __MACTYPES__
  22. #include <MacTypes.h>
  23. #endif
  24.  
  25.  
  26.  
  27. #if PRAGMA_ONCE
  28. #pragma once
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_STRUCT_ALIGN
  40.     #pragma options align=power
  41. #elif PRAGMA_STRUCT_PACKPUSH
  42.     #pragma pack(push, 2)
  43. #elif PRAGMA_STRUCT_PACK
  44.     #pragma pack(2)
  45. #endif
  46.  
  47. /*******************************************************************************
  48.  * 
  49.  * Foundation Types
  50.  *
  51.  */
  52. /* Value of a property */
  53. typedef void *                            RegPropertyValue;
  54. /* Length of property value */
  55. typedef UInt32                             RegPropertyValueSize;
  56. /*******************************************************************************
  57.  * 
  58.  * RegEntryID    :    The Global x-Namespace Entry Identifier
  59.  *
  60.  */
  61.  
  62. struct RegEntryID {
  63.     UInt32                             contents[4];
  64. };
  65. typedef struct RegEntryID                RegEntryID;
  66. typedef RegEntryID *                    RegEntryIDPtr;
  67. /*******************************************************************************
  68.  *
  69.  * Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  70.  *
  71.  *    • Names are a colon-separated list of name components.  Name components
  72.  *      may not themselves contain colons.  
  73.  *    • Names are presented as null-terminated ASCII character strings.
  74.  *    • Names follow similar parsing rules to Apple file system absolute
  75.  *      and relative paths.  However the '::' parent directory syntax is
  76.  *      not currently supported.
  77.  */
  78. /* Max length of Entry Name */
  79.  
  80. enum {
  81.     kRegCStrMaxEntryNameLength    = 47
  82. };
  83.  
  84. /* Entry Names are single byte ASCII */
  85.  
  86. typedef char                             RegCStrEntryName;
  87. typedef char *                            RegCStrEntryNamePtr;
  88. /* length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1*/
  89. typedef char                             RegCStrEntryNameBuf[48];
  90. typedef char                             RegCStrPathName;
  91. typedef UInt32                             RegPathNameSize;
  92.  
  93. enum {
  94.     kRegPathNameSeparator        = ':',                            /* 0x3A */
  95.     kRegEntryNameTerminator        = 0x00,                            /* '\0' */
  96.     kRegPathNameTerminator        = 0x00                            /* '\0' */
  97. };
  98.  
  99. /*******************************************************************************
  100.  *
  101.  * Property Name and ID Definitions
  102.  *    (Applies to all Properties Regardless of NameSpace)
  103.  */
  104.  
  105. enum {
  106.     kRegMaximumPropertyNameLength = 31,                            /* Max length of Property Name */
  107.     kRegPropertyNameTerminator    = 0x00                            /* '\0' */
  108. };
  109.  
  110. typedef char                             RegPropertyNameBuf[32];
  111. typedef char                             RegPropertyName;
  112. typedef char *                            RegPropertyNamePtr;
  113. /*******************************************************************************
  114.  *
  115.  * Iteration Operations
  116.  *
  117.  *    These specify direction when traversing the name relationships
  118.  */
  119. typedef UInt32                             RegIterationOp;
  120. typedef RegIterationOp                     RegEntryIterationOp;
  121.  
  122. enum {
  123.                                                                 /* Absolute locations*/
  124.     kRegIterRoot                = 0x00000002,                    /* "Upward" Relationships    */
  125.     kRegIterParents                = 0x00000003,                    /* include all  parent(s) of entry */
  126.                                                                 /* "Downward" Relationships*/
  127.     kRegIterChildren            = 0x00000004,                    /* include all children */
  128.     kRegIterSubTrees            = 0x00000005,                    /* include all sub trees of entry */
  129.     kRegIterDescendants            = 0x00000005,                    /* include all descendants of entry */
  130.                                                                 /* "Horizontal" Relationships    */
  131.     kRegIterSibling                = 0x00000006,                    /* include all siblings */
  132.                                                                 /* Keep doing the same thing*/
  133.     kRegIterContinue            = 0x00000001
  134. };
  135.  
  136. /*******************************************************************************
  137.  *
  138.  * Name Entry and Property Modifiers
  139.  *
  140.  *
  141.  *
  142.  * Modifiers describe special characteristics of names
  143.  * and properties.  Modifiers might be supported for
  144.  * some names and not others.
  145.  * 
  146.  * Device Drivers should not rely on functionality
  147.  * specified as a modifier.
  148.  */
  149. typedef UInt32                             RegModifiers;
  150. typedef RegModifiers                     RegEntryModifiers;
  151. typedef RegModifiers                     RegPropertyModifiers;
  152.  
  153. enum {
  154.     kRegNoModifiers                = 0x00000000,                    /* no entry modifiers in place */
  155.     kRegUniversalModifierMask    = 0x0000FFFF,                    /* mods to all entries */
  156.     kRegNameSpaceModifierMask    = 0x00FF0000,                    /* mods to all entries within namespace */
  157.     kRegModifierMask            = (long)0xFF000000                /* mods to just this entry */
  158. };
  159.  
  160. /* Universal Property Modifiers */
  161.  
  162. enum {
  163.     kRegPropertyValueIsSavedToNVRAM = 0x00000020,                /* property is non-volatile (saved in NVRAM) */
  164.     kRegPropertyValueIsSavedToDisk = 0x00000040                    /* property is non-volatile (saved on disk) */
  165. };
  166.  
  167. /* ///////////////////////
  168. //
  169. // The Registry API
  170. //
  171. /////////////////////// */
  172. /* ///////////////////////
  173. //
  174. // Entry Management
  175. //
  176. /////////////////////// */
  177.  
  178. /*-------------------------------
  179.  * EntryID handling
  180.  */
  181. /*
  182.  * Initialize an EntryID to a known invalid state
  183.  *   note: invalid != uninitialized
  184.  */
  185. EXTERN_API_C( OSStatus )
  186. RegistryEntryIDInit                (RegEntryID *            id);
  187.  
  188. /*
  189.  * Compare EntryID's for equality or if invalid
  190.  *
  191.  * If a NULL value is given for either id1 or id2, the other id 
  192.  * is compared with an invalid ID.  If both are NULL, the id's 
  193.  * are consided equal (result = true). 
  194.  */
  195. EXTERN_API_C( Boolean )
  196. RegistryEntryIDCompare            (const RegEntryID *        id1,
  197.                                  const RegEntryID *        id2);
  198.  
  199. /*
  200.  * Copy an EntryID
  201.  */
  202. EXTERN_API_C( OSStatus )
  203. RegistryEntryIDCopy                (const RegEntryID *        src,
  204.                                  RegEntryID *            dst);
  205.  
  206. /*
  207.  * Free an ID so it can be reused.
  208.  */
  209. EXTERN_API_C( OSStatus )
  210. RegistryEntryIDDispose            (RegEntryID *            id);
  211.  
  212. /*-------------------------------
  213.  * Adding and removing entries
  214.  *
  215.  * If (parentEntry) is NULL, the name is assumed
  216.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  217.  */
  218. EXTERN_API_C( OSStatus )
  219. RegistryCStrEntryCreate            (const RegEntryID *        parentEntry,
  220.                                  const RegCStrPathName * name,
  221.                                  RegEntryID *            newEntry);
  222.  
  223. EXTERN_API_C( OSStatus )
  224. RegistryEntryDelete                (const RegEntryID *        id);
  225.  
  226. EXTERN_API_C( OSStatus )
  227. RegistryEntryCopy                (RegEntryID *            parentEntryID,
  228.                                  RegEntryID *            sourceDevice,
  229.                                  RegEntryID *            destDevice);
  230.  
  231. /*---------------------------
  232.  * Traversing the namespace
  233.  *
  234.  * To support arbitrary namespace implementations in the future,
  235.  * I have hidden the form that the place pointer takes.  The previous
  236.  * interface exposed the place pointer by specifying it as a
  237.  * RegEntryID.
  238.  *
  239.  * I have also removed any notion of returning the entries
  240.  * in a particular order, because an implementation might
  241.  * return the names in semi-random order.  Many name service
  242.  * implementations will store the names in a hashed lookup
  243.  * table.
  244.  *
  245.  * Writing code to traverse some set of names consists of
  246.  * a call to begin the iteration, the iteration loop, and
  247.  * a call to end the iteration.  The begin call initializes
  248.  * the iteration cookie data structure.  The call to end the 
  249.  * iteration should be called even in the case of error so 
  250.  * that allocated data structures can be freed.
  251.  *
  252.  *    Create(...)
  253.  *    do {
  254.  *        Iterate(...);
  255.  *    } while (!done);
  256.  *    Dispose(...);
  257.  *
  258.  * This is the basic code structure for callers of the iteration
  259.  * interface.
  260.  */
  261. typedef struct OpaqueRegEntryIter*         RegEntryIter;
  262. /* 
  263.  * create/dispose the iterator structure
  264.  *   defaults to root with relationship = kRegIterDescendants
  265.  */
  266. EXTERN_API_C( OSStatus )
  267. RegistryEntryIterateCreate        (RegEntryIter *            cookie);
  268.  
  269. EXTERN_API_C( OSStatus )
  270. RegistryEntryIterateDispose        (RegEntryIter *            cookie);
  271.  
  272. /* 
  273.  * set Entry Iterator to specified entry
  274.  */
  275. EXTERN_API_C( OSStatus )
  276. RegistryEntryIterateSet            (RegEntryIter *            cookie,
  277.                                  const RegEntryID *        startEntryID);
  278.  
  279. /*
  280.  * Return each value of the iteration
  281.  *
  282.  * return entries related to the current entry
  283.  * with the specified relationship
  284.  */
  285. EXTERN_API_C( OSStatus )
  286. RegistryEntryIterate            (RegEntryIter *            cookie,
  287.                                  RegEntryIterationOp     relationship,
  288.                                  RegEntryID *            foundEntry,
  289.                                  Boolean *                done);
  290.  
  291. /*
  292.  * return entries with the specified property
  293.  *
  294.  * A NULL RegPropertyValue pointer will return an
  295.  * entry with the property containing any value.
  296.  */
  297. EXTERN_API_C( OSStatus )
  298. RegistryEntrySearch                (RegEntryIter *            cookie,
  299.                                  RegEntryIterationOp     relationship,
  300.                                  RegEntryID *            foundEntry,
  301.                                  Boolean *                done,
  302.                                  const RegPropertyName * propertyName,
  303.                                  const void *            propertyValue,
  304.                                  RegPropertyValueSize     propertySize);
  305.  
  306. /*--------------------------------
  307.  * Find a name in the namespace
  308.  *
  309.  * This is the fast lookup mechanism.
  310.  * NOTE:  A reverse lookup mechanism
  311.  *      has not been provided because
  312.  *        some name services may not
  313.  *        provide a fast, general reverse
  314.  *        lookup.
  315.  */
  316. EXTERN_API_C( OSStatus )
  317. RegistryCStrEntryLookup            (const RegEntryID *        searchPointID,
  318.                                  const RegCStrPathName * pathName,
  319.                                  RegEntryID *            foundEntry);
  320.  
  321. /*---------------------------------------------
  322.  * Convert an entry to a rooted name string
  323.  *
  324.  * A utility routine to turn an Entry ID
  325.  * back into a name string.
  326.  */
  327. EXTERN_API_C( OSStatus )
  328. RegistryEntryToPathSize            (const RegEntryID *        entryID,
  329.                                  RegPathNameSize *        pathSize);
  330.  
  331. EXTERN_API_C( OSStatus )
  332. RegistryCStrEntryToPath            (const RegEntryID *        entryID,
  333.                                  RegCStrPathName *        pathName,
  334.                                  RegPathNameSize         pathSize);
  335.  
  336. /*
  337.  * Parse a path name.
  338.  *
  339.  * Retrieve the last component of the path, and
  340.  * return a spec for the parent.
  341.  */
  342. EXTERN_API_C( OSStatus )
  343. RegistryCStrEntryToName            (const RegEntryID *        entryID,
  344.                                  RegEntryID *            parentEntry,
  345.                                  RegCStrEntryName *        nameComponent,
  346.                                  Boolean *                done);
  347.  
  348. /* //////////////////////////////////////////////////////
  349. //
  350. // Property Management
  351. //
  352. ////////////////////////////////////////////////////// */
  353. /*-------------------------------
  354.  * Adding and removing properties
  355.  */
  356. EXTERN_API_C( OSStatus )
  357. RegistryPropertyCreate            (const RegEntryID *        entryID,
  358.                                  const RegPropertyName * propertyName,
  359.                                  const void *            propertyValue,
  360.                                  RegPropertyValueSize     propertySize);
  361.  
  362. EXTERN_API_C( OSStatus )
  363. RegistryPropertyDelete            (const RegEntryID *        entryID,
  364.                                  const RegPropertyName * propertyName);
  365.  
  366. EXTERN_API_C( OSStatus )
  367. RegistryPropertyRename            (const RegEntryID *        entry,
  368.                                  const RegPropertyName * oldName,
  369.                                  const RegPropertyName * newName);
  370.  
  371. /*---------------------------
  372.  * Traversing the Properties of a name
  373.  *
  374.  */
  375. typedef struct OpaqueRegPropertyIter*     RegPropertyIter;
  376. EXTERN_API_C( OSStatus )
  377. RegistryPropertyIterateCreate    (const RegEntryID *        entry,
  378.                                  RegPropertyIter *        cookie);
  379.  
  380. EXTERN_API_C( OSStatus )
  381. RegistryPropertyIterateDispose    (RegPropertyIter *        cookie);
  382.  
  383. EXTERN_API_C( OSStatus )
  384. RegistryPropertyIterate            (RegPropertyIter *        cookie,
  385.                                  RegPropertyName *        foundProperty,
  386.                                  Boolean *                done);
  387.  
  388. /*
  389.  * Get the value of the specified property for the specified entry.
  390.  *
  391.  */
  392. EXTERN_API_C( OSStatus )
  393. RegistryPropertyGetSize            (const RegEntryID *        entryID,
  394.                                  const RegPropertyName * propertyName,
  395.                                  RegPropertyValueSize *    propertySize);
  396.  
  397. /*
  398.  * (*propertySize) is the maximum size of the value returned in the buffer
  399.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  400.  * value returned.
  401.  */
  402. EXTERN_API_C( OSStatus )
  403. RegistryPropertyGet                (const RegEntryID *        entryID,
  404.                                  const RegPropertyName * propertyName,
  405.                                  void *                    propertyValue,
  406.                                  RegPropertyValueSize *    propertySize);
  407.  
  408. EXTERN_API_C( OSStatus )
  409. RegistryPropertySet                (const RegEntryID *        entryID,
  410.                                  const RegPropertyName * propertyName,
  411.                                  const void *            propertyValue,
  412.                                  RegPropertyValueSize     propertySize);
  413.  
  414. /* //////////////////////////////////////////////////////
  415. //
  416. // Modifier Management
  417. //
  418. ////////////////////////////////////////////////////// */
  419. /*
  420.  * Modifiers describe special characteristics of names
  421.  * and properties.  Modifiers might be supported for
  422.  * some names and not others.
  423.  * 
  424.  * Device Drivers should not rely on functionality
  425.  * specified as a modifier.  These interfaces
  426.  * are for use in writing Experts.
  427.  */
  428. /*
  429.  * Get and Set operators for entry modifiers
  430.  */
  431. EXTERN_API_C( OSStatus )
  432. RegistryEntryGetMod                (const RegEntryID *        entry,
  433.                                  RegEntryModifiers *    modifiers);
  434.  
  435. EXTERN_API_C( OSStatus )
  436. RegistryEntrySetMod                (const RegEntryID *        entry,
  437.                                  RegEntryModifiers         modifiers);
  438.  
  439. /*
  440.  * Get and Set operators for property modifiers
  441.  */
  442. EXTERN_API_C( OSStatus )
  443. RegistryPropertyGetMod            (const RegEntryID *        entry,
  444.                                  const RegPropertyName * name,
  445.                                  RegPropertyModifiers *    modifiers);
  446.  
  447. EXTERN_API_C( OSStatus )
  448. RegistryPropertySetMod            (const RegEntryID *        entry,
  449.                                  const RegPropertyName * name,
  450.                                  RegPropertyModifiers     modifiers);
  451.  
  452. /*
  453.  * Iterator operator for entry modifier search
  454.  */
  455. EXTERN_API_C( OSStatus )
  456. RegistryEntryMod                (RegEntryIter *            cookie,
  457.                                  RegEntryIterationOp     relationship,
  458.                                  RegEntryID *            foundEntry,
  459.                                  Boolean *                done,
  460.                                  RegEntryModifiers         matchingModifiers);
  461.  
  462. /*
  463.  * Iterator operator for entries with matching 
  464.  * property modifiers
  465.  */
  466. EXTERN_API_C( OSStatus )
  467. RegistryEntryPropertyMod        (RegEntryIter *            cookie,
  468.                                  RegEntryIterationOp     relationship,
  469.                                  RegEntryID *            foundEntry,
  470.                                  Boolean *                done,
  471.                                  RegPropertyModifiers     matchingModifiers);
  472.  
  473.  
  474.  
  475. #if PRAGMA_STRUCT_ALIGN
  476.     #pragma options align=reset
  477. #elif PRAGMA_STRUCT_PACKPUSH
  478.     #pragma pack(pop)
  479. #elif PRAGMA_STRUCT_PACK
  480.     #pragma pack()
  481. #endif
  482.  
  483. #ifdef PRAGMA_IMPORT_OFF
  484. #pragma import off
  485. #elif PRAGMA_IMPORT
  486. #pragma import reset
  487. #endif
  488.  
  489. #ifdef __cplusplus
  490. }
  491. #endif
  492.  
  493. #endif /* __NAMEREGISTRY__ */
  494.  
  495.